MacWorld: Complete Mac Interactive/Macworld Complete Mac Interactive CD)(1994).iso/The Best of BMUG/Utilities/Control Panels and Extensions/ClipboardMagician.76/About Clipboard Magician

Text File | 1990-12-11 | 28KB | 167 lines

Clipboard Magician 0.65                                1990-12-11
                                                        by Ed Lai
• not an Apple Computer, Inc. product •     [e-mail], AppleLink: Lai1
-----------------------------------------------------------------
•••  dedicated to all those, who fight for democracy in China •••
-----------------------------------------------------------------

The goal of CM 0.65 is to make easier to work with other application. The reason that CM chooses to work with the clipboard is that it is possible to use CM functionality from any application through the clipboard. However very often you still have to go through the following steps:
1. Select the data of interest to you in your application and then do copy.
2. Invoke the DA.
3. Select and perform the operation.
4. Close the DA to get back to your application.
5. Paste the result in.

Potentially you can do all these with a single key stroke in 0.65.

For this purpose there are two new FKEYs that can be used with CM.

FKEY 6 just invokes CM. So you can get to CM with a single key stroke.

FKEY 5 copy the content of the current selection in your application
into the clipboard and then invoke FKEY 6. This means that if you use FKEY 5, CM would be invoked with the content of the current selection in your application.

So these FKEYs combines steps 1 and 2 into a single key stroke.

CM now remembers the last operation you did, on the assumption you
are very likely to do it again. It will be the default selection whenever the data type matches.

So if you want to apply the last operation one more time using the FKEYs, the amount of work required in step 3 is reduced.

We have added two new checkboxes. With a total of 5 checkboxes it is getting to be a bit crowded so the checkbox  text has to be greatly shortened. However the five checkbox will be duplicated by a menu item with a fuller title. While this is a duplication, the reason for doing this is that there is wide spread disagreement on the first prototype whether an item should be a checkbox or on the menu. If it is on a checkbox it gives visual feedback of the state and it can be accessed quickly with the mouse. If it is on the menu, the title can be longer and it can be invoked from the keyboard with a command key (starting with 0.65 keyboard shortcut on the CM menu will be handled even though I have not put any up there, you can add it yourself). So with the duplication you can have it both ways.

The first of the check box is Auto-run. If this is on then when the DA is first opened, if the last operation on the clipboard can be operated on by the last operation you did on CM, it would be invoked automatically. This would simplify step 3 above even further. However initial feedback is while this is powerful its is also dangerous because you may not remember what your last operation is and you are plunging into the unknown. The answer to  that is that this is an option that you should turn on only on special situation. Then you repeat the operation a number  of times and then turn it off again so you need not remember what was your last operation on CM 2 weeks ago before your vacation. Furthermore this option is now more restrictive than the first prototype (I may relax them again in future depending on the feedback on this version). It would only occur if the DA is not yet opened. And after you select this option the option would be turned off automatically if you select some other operation after that. The idea being that you want to select the auto-run option right after an operation when your mind is still fresh about what that operation is. If you go on to do some other things, you may not remember it so we turn it off for you. As an additional reminder what this operation is, you can pull down the CM menu to see exactly what the name of the operation is.

So with auto-run, we can eliminate step 3 above, now we want to eliminate step 4 and 5. This is the purpose of the other new checkbox Auto-quit. If both auto-run and auto-quit are selected, then after the auto-run is successfully  executed, the DA would close itself and post a command-V so that the clipboard data will be pasted back into your application's selection.

So now it is possible to perform step 1 to step 5 with a single keystroke using FKEY 5. It look just like it is an extension of your application. Actually the integration could even be better. Currently it still goes through every step as if you have invoked a macro to bring up the DA, select the operation and close it so you are aware that you are doing it through a DA. A lot of these could have been bypassed so you may not realize that this is functionality from somewhere else, and the performance would be much better, but this will not be attempted in this version.

One question remains, if CM is on such auto-pilot, how can you regain control so that you can do something else with it. You can do that by holding down the shift key when you invoke CM, then the auto-run will not be executed. However do not hold down the command key at the same time. This is because command + shift key down would not disable auto-run so that FKEY 5 would still work even if you hold down the command shift keys for too long.

Another new feature is that when you are in CM, after you have done various thing you have decided to execute an operation will bring you a result that can be pasted back to your application. Then execute that operation with the command key down, that would execute the operation, close the DA and post a command-V.
If the DA is run under system 7, the coercion routine in the AppleEvents manager will be used to convert the numeric data type into text string.

These are the new features in the DA. As for the CNVTs in the Magic Wand file, there are relative few changes.

In the Edit Big file with no Wrap around, there is a very serious bug that double click to select a word crashes the system. As a temporary fix I have disabled double click but but I forgot to put it in version 0.64, so I put it in this time. In the print text CNVT, it has been extended to do multiple "columns". When you invoke it using the options keys, one of the option would be a layout that you can pick. The layout is just a 'nrct' resource so you can make your own custom one by editing the resource (where each rectangle represents a "column" all of which must have the same width, and if there is a rectangle that enclose all other rectangles then that enclosing rectangle is not used for printing but will be used to represents the page so that there can be margins for the "columns").

There is a new CNVT to convert an error number into a text string. This will also be used by CM to return more meaningful error message. However the list of errors is far from complete but may be added by ResEdit.

We have a contribution from Maf Vosburgh to dither color picture to B/W.

Gestalt let you find out about the Gestalt of your system, the four letter code should be TEXT data in the clipboard.
AECoerce can be used if you have system 7 to do a conversion using AppleEvents Manager's coercion routines.
AToB let you do the AToB decoding used in some UNIX system.
SGB to HGB conversion let you convert data from pre-6.03 Simplified Chinese system to 6.0x system.
You may put a name in the clipboard and then get a resource with that name using a new CNVT.

As we have more and more CNVTs, keeping track of version is more and more painful, especially when we have deleted unused ones and add new customized ones. Also adding through ResEdit is painful because we are often adding a group of resources and they may need renumbering. So we add a installer utility this time. This is just the first time it is introduced so it is going to be a bit rough on the edges and it has been barely tested. It is model after the familiar model of font-DA mover so it should be easy to use. Like font-DA mover you should hold down option key to open a file if its file type is different from that of the magic wand. When you copy a CNVT over if the name already exists it would give you a warning and another warning if you try to replace a newer version to reduce the chance of mistake. Also any undated CNVT is considered to be very new to be on the safe side. When you copy a list of CNVTs, you may choose to always have such confirmations or ignore them automatically. Like DA movers, resource number will be assigned automatically. Very often names have been renamed or localized, so the utility cannot completely rely on the name to tell things apart. We shall use the rule that we use the 8 character tag ID to distinguish CNVTs, and only if the 8 byte tag is absent then we use the name. If you have localized the name or change it in some other way the tag name would still be same. We know you probably want to keep using the same name so the utility would not change that name even if it is different from the source file.


----------------------------------

About Clipboard Magician 0.64, 90-5-24.

The most important feature of this version of Clipboard Magician is that there is a protocol to support code resource other than CM's private type of 'CNVT'. Besides supporting a few popular code resources, it also enable the definition of a new code resource which is a batch file for a list of commands to be executed.

In this version of the CM commands are now listed alphabetically.  Furthermore, one can now select a command by typing in the first few letters as in any standard file dialog. For those who like to do everything from the keyboard, it is possible to use the tab key to switch between the clipboard view and the command view, and the esc key (shift tab or option tab if your keyboard does not have an esc key) to switch between data specific commands and commands that do not operate on any data. Thanks to Ian Feldman for these suggestion and other valuable contribution to CM.

There are several new menu items:
'page setup' - just like in most other applications.
'Do To All Data' -  if there are more than one piece of data in the clipboard, this would apply the selected command to every piece of data instead of just the selected data.
'Delete This Operation' - This is used to delete a code resource and all resources belong to that code resource according to the CM convention.
`Start chaining/ End chaining' - see below.

This last one is used to define a custom command, formed by  selective chaining of a sequence of needed function commands. For example, a 'PICT' might be rotated by first converting it to a bitmap image ('bmap'), then rotating and, finally, converting it back to a 'PICT'.  If one does this often, then a special compound-operation command can be defined.  This is achieved by making CM remember the proper sequence of commands;  in this case -- put a 'PICT' in the clipboard, then choose the  'Start chaining' menu item.  Now do the commands in desired sequence, i.e.  convert to bmap, rotate, convert to PICT. Terminate the chaining process by selecting `End chaining'.

Next you'll be asked to name the new command, and enter information about the operation.  From now on, if you have a 'PICT' in the clipboard, you should see your custom command in the list of operations in the main window, among the ones that can be executed on the given resource type.  Selecting it will execute all the commands in the defined sequence.  Selecting it with the option key makes it step through the individual commands, for control or debugging purposes. However the "do it to all data" option is not registered in the chain in this version of CM.

Among the issues that this particular version of CM tries to solve is that of localization.  The commands' names may now be changed at will, to a foreign language or accordingly to taste.  However, commands DO call each other and if they are changed, they may no longer find one another.  With the ability to chain commands together, this problem become even more acute.  In this version, names of other commands are given an eight byte language independent signature so that it should be possible to call any renamed one in a language-independent way.  The proper signature can be found in the "About this operation" dialog (although not all commands have been assigned signatures yet).

The chain-command feature is implemented in such a way that the CM's architecture becomes wide open.  In previous versions, the commands were all CNVT code resource with certain calling conventions.  This, my latest, architecture makes any type of a code resource (with any calling convention) potentially usable by the CM.  Of course, it is not my philosophy to have built-in support for every single type of resource.  In this version there is still built-in direct support for only one kind of resources, that of the `CNVT' type.  However, now it is entirely possible to have other resources execute by means of appropriately written adapter CNVTs.  This is how the new command chaining is implemented.

Using the same mechanism, a few more resources types are now supported. They are XCMDs, XCFNs, FKEYs, VCMDs and VFILs.  Of course, since you are running within a DA and not in Hypercard proper, many XCMDs will not work, if they expect to query HyperCard during the execution (ie, call back to get a field by ID or similar).  Do expect a lot of XCMD and VCMDs not to work and even crashes when they try to access facilities available in their original environment but not available in CM. However, if the calls that they use are of fairly generic type, such as ones to convert a number to string, then the XCMD can be used here as well.  The XCMD must be first renamed to follow the CM-calling conventions though (This is also true of using any other code resources).  If, say, the original XCMD is called by 'xyz', then it should be copied and saved into the Magic Wand, renamed either as a 'TEXTxyz' resource, a '****xyz' or '____xyz' (if it doesn't require any arguments).  Study the (supplied here as an example only) original HyperCard 'Flash' XCMD, now called via the 'TEXTFlash' CM-command: entering the number '4' into the clipboard will make a 'Flash' appear as a possible "conversion" command in the CM's main window.  Selecting it passes the clip- board held argument to the embedded FlashXCMD, that will then flash the DA window 4 times.  This particular XCMD might not be that useful but, given the large number of XCMD available, I am sure that this feature will find its use.  For example, it helped me a lot when I was documenting the CNVT by running the XFCN 'Resource()'to return resource names for CNVT, prior to sorting/inventorying.

As each CNVT are being improved, it is difficult to know whether you are replacing a new version with an older version since there is no version information. In this version of CM, the create date of the resource is used as the version. This is append to the CNV! string. You can get the date from the "About This Operation" command. Also sometime it is useful to know what kind of result a CNVT may return. This information is also put into the CNV! and is shown by the "About This Operation".

Highlights of some of the new CNVTs

'bmap' is the bitmap data, for which there is now a simple fat-bits editor; flipping and 90-degree rotation of bitmaps is also possible.  Resources of type ICON/ SICN/ PICT can now be easily changed to and from 'bmap' prior to editing, and then converted back to their original resource types.  Now one can also capture a portion of the screen and make it into a PICT (in monochrome 1-bit-per-pixel only).  Any block of memory can now be read in.  One may also enter special characters, using the C convention of \n \f etc (plus \$XX for hexadecimal) and then converting the strings to proper bytes.  A number of other CNVT resources uses this particular CNVT for their own entry needs for special characters -- like the Munger, the toolbox Munger call, that can be used to insert, delete or replace blocks of binary data. You can transpose a string of text into reverse order. Data can be sent through the serial port, and if you have a modem there and you configure the command right (as usual by holding down the option key and the command is invoked), you can use that to dial a number. You can now test a FKEY by copying it into the clipboard and then execute it. You can invoke FKEYs installed in the system folder. Since this feature is implemented as an FKEY, you can also used this FKEY (look for the FKEY with the name "___Invoke other FKEY") as an ordinary FKEY if you wish. This permits you to have more than the 10 FKEYs by assigning names to other FKEYs. This is not as nice as popkeys but is a little safer since no INIT is involved. We have two CNVTs - "Read EPSF file" and "Polygonize" that are contributed by Anders Blomdell. With Read resources, it is now possible to read more than one resource at a time.

----------------------------------

About Clipboard Magician 0.55, 89-9-8.

In view of what has been happening in China, I am dedicating this program to all those who are fighting for democracy in China.

There is only minor modification of the DA from version 0.5 to 0.55. The change is made mainly so that an operation can now return a list of data rather than a single piece of data. The visiable change to the DA is that now the number of bytes in the data selected is displayed. If an operation has failed, an error number is also displayed (of course this will be change to error message in future).

The major change is more new components have been added. Now there are over 40 components with a total size of 87K. I shall give a list of all the components.

Convert ICON to PICT.
Convert PICT to ICON.
Convert CURS to PICT.
Convert PICT to ICON.
Reduce PICT to its edge.
Convert PICT to SICN - from PICT to 16x16 bit map.
Convert MWRT to TEXT - MacWrite data to plain text.
Change carriage return in text to space.
Remove line feed character from text.
Save a PICT as PICT file.
Read Text file into scrap.
Read PICT file into scrap.
Hexdump the data.
Get file info.
Convert STR to TEXT.
Convert ICN# to PICT.
Play a snd  resource sound.
Rename the data type.
Print a PICT.
Print the TEXT; hold down option key to change font and size.
Edit the text - function is about that of TeachText; hold down option key to change font and size.
Read data fork of a file into scrap.
Consider ICN# to be a list of icons and pick an icon out of the list.
Read a resource from a file into the scrap.
Save data as resource in an existing file.
Pack hexdecimal digits.
Save data into the data fork of a new file.
Sort text lines.
Append data to the data fork of an existing file.
Read a MacPaint file into scrap as PICT.
Select an area out of a PICT.
Transliterate text - See inside Mac, vol 5, p311.
Convert HyperCard card fields and buttons into a dialog item list DITL.
Replace text string, uses Grep library from Capps'™ of Think Technologies Inc.
Rotate SICN the 16 by 16 bit map.
Rotate ICN#, a list of icons.
Convert Shifted GB code Chinese character to GB code.
Convert GB code to Shifted GB code Chinese character.
Edit big text data that has no need of wrap around, uses PEEdit library from Capps'™ of Think Technologies Inc. Hold down option key to change font and size
Generate some text and put it into scrap.
Convert dialog item list DITL to view resource for use in MACAPP 2.0.
Convert dialog item list DITL to a HyperCard card.
Edit data according to a template, template is in same format as that of ResEdit. Read ResEdit manual for more details. There is also an extension to the template types. BBYT is boolean in a single byte. ATPX where x is '0'-'9' is align to the power. So ATP5 means align to the 2 ** 5 = 32 bytes, and 0 is treated as 10. No editing allowed if size of data is large. Hold down option key if you want to edit without a template (edit the hex dump).
----------------------------------
About Clipboard Magician 0.5, 89-4-6.

The Clipboard Magician is a prototype written to explore certain concepts. I have worked on and off on the project, never quite finishing it.  However I have been using it myself daily without serious problem. I feel even in its present form it can be useful to many users. So I am releasing it as freeware. You may copy it and use it freely, but it may not be redistributed as a commercial product. Apple computer Inc. retains the copyright. NOTE THAT THIS IS NOT AN OFFICIALLY RELEASED PRODUCT FROM APPLE COMPUTER INC SO DO NOT EXPECT IT TO HAVE THE QUALITY AND ROBUSTNESS YOU NORMALLY EXPECT FROM PRODUCTS FROM APPLE COMPUTER INC., NOR EXPECT ANY SUPPORT ON THIS PROGRAM FROM APPLE COMPUTER INC.

The Clipboard Magician is a desk accessory that displays the scrap. It is just like a clipboard but it also allows you to manipulate the data there. The basic concept is that application should not be required to copy multiple representation to the scrap. Rather an application can copy the most meaningful information to the scrap, and tools can be used to transform it to other desired form. The Clipboard Magician cannot pull a rabbit out of the clipboard, but if you put an ICON into it, you can pull a PICT out of it. That is why it is called Clipboard Magician. (Earlier I have used the name Alchemist, the theme is similar). If you have copied an ICON using ResEdit, the current Finder Clipboard will not show it, neither will the scrapbook. However the Clipboard Magician would just transform it into a picture and show it.

Of course we would need more tools as new data type are introduced. Hence there is no fixed set of tools. Rather the tools are software components - XCMD like code resource - that are installed into a file called "Magic Wand" that should be placed in the system folder. So if you need to display a CURS, you need to get a CURS to PICT components. As needs arises, I have written a number of components for my own use. They are written in a quick and dirty manner (some are written in a few minutes) and certainly nothing worth bragging about individually. Do not judge the concept of the Clipboard Magician by the quality of component tools available here. They are no more than examples hinting what can be done. Hopefully better versions will be written and since they are components they can be replaced any time. Collectively they still represent a useful collection of tools that is available to the user anytime. This is especially useful if you are not running MultiFinder. I interpret the word conversion very broadly. PICT to ICON and ICON to PICT obviously are conversions. Removing line feeds from text data is also a conversion. So are text editing, text printing, picture printing, saving scrap data to file (either data fork or resource), reading data (either data fork or resource) into scrap (so you can hunt for ICONs from various applications), read a PICT/PAINT file to scrap, get file information, do a hex dump, undo a hex dump, play a 'snd ', all available from a single DA. And if you are willing to  program the component or someone else is doing it, it can be added to the list.

Install the Clipboard Magician DA and put the file "Magic Wand" into the system folder and you are ready to use it. When you open Clipboard Magician DA, there will be a list of all the data in the scrap, the data type is on the list so that you know what you are looking at. The main frame of the DA doubles as the clipboard view and command list, the default being the clipboard view. The two views can be toggled using the menu command Show Command/Show Clipboard View. A mouse click on the clipboard view also toggles it to the command view. If there are multiple data on the scrap, the view is selected by the selection in the list on the left. The commands also depend on the data type selected since different set of commands are available for different data types. If no data type is selected (this can also be done by selecting "generate new data" from the menu), then the command list will be those that generate data rather than operate on data, e.g. read MacPaint file into scrap. There is a check box on the DA to control whether picture will be shown as actual size or scaled to fit. Even in the background the DA would check for new content in the scrap periodically. So for an application that does not implement a clipboard and copies directly to the public scrap rather than keeping a private scrap, you can use the Clipboard Magician as a substitute clipboard. However to do this you should launch Clipboard Magician in the application partition under multifinder. One example is ResEdit. ResEdit copies to the public scrap, does not have a clipboard,  and does not generate extra PICT scrap data when ICON, CURS etc are copied. The Clipboard Magician would work nicely here as a clipbboard. If the Clipboard Magician is present in every system, no future application needs to implement a clipboard of its own.

When a command is selected, if the About this operation menu item is enabled, you can find out more about the command. To execute the command, you hit the "Do it" button (or double click on the command, or hit the return key). Normally the scrap will be cleared and the scrap will contain the new converted data. This can be changed by the checkbox so that the new data will be appended to the end of scrap. There are a few commands, like the text editor, that use certain default parameters (Font and size in this example). If you want to change the default, you should hold down the option key when you invoke the command.

There is currently no installer program for the components, so you have to use ResEdit to put it into file "Magic Wand" (I think you can even use the Clipboard Magician tools to do it if you are brave enough). The components are either of resource type CNVT or XRTN where the former are visible to the user and the latter is not accessible directly but may be used by the CNVT components. By convention the resource IDs are multiple of 32 and components with resource ID N would own all the resource with ID between N and N+31 (is that too few or too many?). The resource name of CNVT has to follow certain convention so be careful when you try to translate it into a foreign language. The first four byte is the data type that the command can operate on (or ____ if it does not operate on any data, or **** if can operate on any kind of data as in the case of hexdump). If the fifth byte is '>' followed by four more bytes, then it is a data conversion component and should not be renamed. Otherwise the rest is just the command name and you can change or translate it. However some of the components may be called by other components by name (in particular the text and pict printing components are called by the Clipboard Magician to print the clipboard), changing the name may make other components fail.

In a sense the paradigm is a pseudo-object-oriented approach where the data type is the class, '****' is the superclass. You select an object and the methods (including those inherited from the superclass) are presented. It is a nice paradigm. However there are newer applications that paste different types of data to the scrap where one is the supplement of the other. An example is 'styl'. Then the current paradigm breaks down. Fortunately they are comparatively rare. Actually this comes about because the convention of writing multiple sets of data to the scrap is wasteful and this is used as a way of getting around the problem. This won't be necessary if we follow the Clipboard Magician paradigm where application just write out the richest data type, and the Clipboard Magician would convert it to a form acceptable by other applications.

The Clipboard Magician requires the 128K ROM. The DA is about 10K. The current magic wand file is 31K and contains 30 components, only a few needs to be in memory at the same time. There is a separate document on how to program CNVTs.

Send bug report or comments or new components to
Ed Lai
[e-mail]
AppleLink: Lai1